5. API Documentation-API文档 - 5.2 The clientutils module-clientutils模块 - 《CasperJS中文文档（个人翻译）》

clientutils 模块
- 提示
书签
- 提示
ClientUtils 原型
visible()

clientutils 模块

Casper附带了一些注入远程DOM环境的客户端实用程序，并可通过clientUilils模块的ClientUtils类的utils对象实例从那里访问：

casper.evaluate(function() {
  __utils__.echo("Hello World!");
});

提示
提供这些工具是为了避免将CasperJS与任何第三方库（如jQuery，Mootools或某些东西）相耦合，但是你可以随时使用这些工具，并设置Casper.options.clientScripts选项让这些工具在客户端可用。

书签

还可以使用一个小书签来帮助您在最喜欢的浏览器的DOM中注入Casper的客户端实用程序。

只需将以下链接拖到你的收藏夹toobar;当你点击它时，utils对象将在浏览器的控制台中可用：CasperJS Utils

提示
由于CasperJS和PhantomJS基于Webkit，强烈建议你使用最新的Webkit兼容浏览器来使用此书签（Chrome，Safari等）

ClientUtils 原型

echo()

调用方法：echo(String message)

版本1.0新增

从远程页面DOM环境向casper控制台输出消息：

casper.start('http://foo.ner/').thenEvaluate(function() {
    __utils__.echo('plop'); // this will be printed to your shell at runtime
});

encode()

调用方法：encode(String contents)

此方法使用base64算法对字符串进行编码。对于记录，CasperJS不使用内置的window.btoa（）函数，因为它不能有效地处理使用> 8b字符编码的字符串：

var base64;
casper.start('http://foo.bar/', function() {
    base64 = this.evaluate(function() {
        return __utils__.encode("I've been a bit cryptic recently");
    });
});
casper.run(function() {
    this.echo(base64).exit();
});

exists()

调用方法：exists(String selector)

检查与给定选择器表达式匹配的DOM元素是否存在：

var exists;
casper.start('http://foo.bar/', function() {
    exists = this.evaluate(function() {
        return __utils__.exists('#some_id');
    });
});
casper.run(function() {
    this.echo(exists).exit();
});

findAll()

调用方法： findAll(String selector)

检索与给定选择器表达式匹配的所有DOM元素：

var links;
casper.start('http://foo.bar/', function() {
    links = this.evaluate(function() {
        var elements = __utils__.findAll('a.menu');
        return elements.map(function(e) {
            return e.getAttribute('href');
        });
    });
});
casper.run(function() {
    this.echo(JSON.stringify(links)).exit();
});

findOne()

调用方法：findOne(String selector)

通过选择器表达式检索单个DOM元素：

var href;
casper.start('http://foo.bar/', function() {
    href = this.evaluate(function() {
        return __utils__.findOne('#my_id').getAttribute('href');
    });
});
casper.run(function() {
    this.echo(href).exit();
});

forceTarget()

调用方法：forceTarget(String selector, String target)

强制引擎使用另一个目标而不是提供的目标。这对于限制打开的窗口数量并减少内存消耗非常有用：

casper.start('http://foo.bar/', function() {
    var href = this.evaluate(function() {
        return __utils__.forceTarget('#my_id', '_self').click();
    });
    this.echo(href);
});
casper.run(function() {
    this.exit();
});

getBase64()

调用方法:getBase64(String url[, String method, Object data])

此方法将检索url后面的任何资源的base64编码版本。例如，我们假设我们想要检索一些网站logo的base64表示:

var logo = null;
casper.start('http://foo.bar/', function() {
    logo = this.evaluate(function() {
        var imgUrl = document.querySelector('img.logo').getAttribute('src');
        return __utils__.getBase64(imgUrl);
    });
});
casper.run(function() {
    this.echo(logo).exit();
});

getBinary()

调用方法:getBinary(String url[, String method, Object data])

该方法将检索给定二进制资源的原始内容，不幸的是，PhantomJS无法直接处理这些数据，因此您必须在远程DOM环境中处理这些数据。如果您打算下载资源，请改用getBase64()或Casper.base64encode()。

casper.start('http://foo.bar/', function() {
    this.evaluate(function() {
        var imgUrl = document.querySelector('img.logo').getAttribute('src');
        console.log(__utils__.getBinary(imgUrl));
    });
});
casper.run();

getDocumentHeight()

调用方法: getDocumentHeight()

版本1.0新增

检索当前文档高度：

var documentHeight;
casper.start('http://google.com/', function() {
    documentHeight = this.evaluate(function() {
        return __utils__.getDocumentHeight();
    });
    this.echo('Document height is ' + documentHeight + 'px');
});
casper.run();

getElementBounds()

调用方法: getElementBounds(String selector)

检索与提供的选择器匹配的DOM元素的边界。

它返回一个Object，其中包含四个键：top，left，width和height;如果不存在匹配的元素，则返回null。

getElementsBounds()

调用方法: getElementsBounds(String selector)

检索与提供的选择器匹配的所有DOM元素的边界。

它返回一个对象数组，每个对象都有四个键：顶部，左边，宽度和高度。

getElementsByXPath()

调用方法: getElementByXPath(String expression [, HTMLElement scope])

检索与给定XPath表达式匹配的单个DOM元素。

版本1.0新增

scope参数允许设置执行XPath查询的上下文：

// will be performed against the whole document
__utils__.getElementByXPath('.//a');
// will be performed against a given DOM element
__utils__.getElementByXPath('.//a', __utils__.findOne('div.main'));

getFieldValue()

调用方法: getFieldValue(String selector[, HTMLElement scope])

版本1.0新增

以name为参数检测input域中的值：

<form>
    <input type="text" name="plop" value="42">
</form>

用该方法获取plop的值：

__utils__.getFieldValue('[name="plop"]'); // 42

getFormValues()

调用方法: getFormValues(String selector)

版本1.0新增

检索给定的表单及其所有字段值:

<form id="login" action="/login">
    <input type="text" name="username" value="foo">
    <input type="text" name="password" value="bar">
    <input type="submit">
</form>

要获取表单值：

__utils__.getFormValues('form#login'); // {username: 'foo', password: 'bar'}

log()

调用方法: log(String message[, String level])

你可以选择记录的级别。我们将CasperJS的消息格式化为能与phantomjs匹配的格式。记录的默认级别是debug：

casper.start('http://foo.ner/').thenEvaluate(function() {
    __utils__.log("We've got a problem on client side", 'error');
});

makeSelector()

调用方法: makeSelector(String selector [, String type])

版本1.1-beta5新增

通过定义的类型XPath，Name或Label进行选择。函数与用于XPath类型的Casper模块中的selectXPath具有相同的结果 - 它生成XPath对象。 Function还接受表单字段的名称属性，或者可以通过其标签文本来选择元素。

参数type的值可以是：

css

CSS3选择器 - 选择器将直接被返回
‘xpath’ || null

XPath选择器-将返回XPath对象
‘name’ || ‘names’

选择特定名称的输入，内部隐藏到CSS3选择器
‘label’ || ‘labels’

选择特定标签的输入，由于选择器是标签的文本使用，在内部转换成XPath选择器。

举个例子：

__utils__.makeSelector('//li[text()="blah"]', 'xpath'); // return {type: 'xpath', path: '//li[text()="blah"]'}
__utils__.makeSelector('parameter', 'name'); // return '[name="parameter"]'
__utils__.makeSelector('My label', 'label'); // return {type: 'xpath', path: '//*[@id=string(//label[text()="My label"]/@for)]'}

mouseEvent()

调用方法: mouseEvent(String type, String selector, [Number|String X, Number|String Y])

将鼠标事件分派给提供的选择器后面的DOM元素。

支持的事件有：mouseup, mousedown, click, dblclick, mousemove, mouseover, mouseout, mouseenter, mouseleave 和 contextmenu：

.. index:: XPath

removeElementsByXPath()

调用方法: removeElementsByXPath(String expression)

删除与给定的XPath表达式匹配的所有DOM元素。

sendAJAX()

调用方法: sendAJAX(String url[, String method, Object data, Boolean async, Object settings])

版本1.0新增

按照以下的参数发送AJAX请求：

url:请求的路径
method:请求的方法（默认：GET）
data:发送的数据（默认：null）
async:请求是否同步(默认：false)
setting:自定义AJAX发送时的头信息（默认：null），警告：此处无效的头可能会使请求失败。

警告
不要忘记在CLI调用中传递--web-security = no选项，以便在需要时执行跨域请求：

var data, wsurl = 'http://api.site.com/search.json';
casper.start('http://my.site.com/', function() {
    data = this.evaluate(function(wsurl) {
        return JSON.parse(__utils__.sendAJAX(wsurl, 'GET', null, false));
    }, {wsurl: wsurl});
});
casper.then(function() {
    require('utils').dump(data);
});

setFieldValue()

调用方法: setFieldValue(String|Object selector, Mixed value [, HTMLElement scope])

版本1.1-beta5新增

通过CSS3或XPath选择器设置值以形成字段。使用makeSelector（）函数可以方便地使用name或label选择器。

选项

(String|Object) scope: selector :

具体的表单范围

例子：

__utils__.setFieldValue("input[name='email']", 'chuck@norris.com');
__utils__.setFieldValue("input[name='email']", 'chuck@norris.com', {'formSelector': '#myform'});
__utils__.setFieldValue(__utils__.makeSelector('email', 'name'), 'chuck@norris.com');

visible()

调用方法: visible(String selector)

检查某个元素是否可见：

var logoIsVisible = casper.evaluate(function() {
    return __utils__.visible('h1');
});